textlint による文章校正への対応について【CCG執筆者向け】

川原征大

2023.08.15

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

このブログについて

本ブログはナレッジサイトである Classmethod Cloud Guidebook(CCG) ¹ の執筆者向けに連携したガイドです。 textlint の活用で一般に参考になる部分もあるため、ブログにて公開しています。

CCGのコンテンツを管理している GitHubリポジトリ上では、文章校正ツールである textlint を活用しています。

執筆活動で textlint 指摘が出てきた際の、対応ガイドをまとめます。

textlint は文章校正ツールです。 Node.js のパッケージとして提供されています。

公開されている様々なルールを適用してカスタマイズ可能です。例えば、表記ゆれやタイポを検出できます。

DevelopersIOでも解説ブログがあるので、適宜参照ください。

文章の品質を一定以上に保つ ために活用しています。

CCGは社内の複数エンジニアによる貢献(執筆)で成り立っています。文章の特性、書きっぷりには個人差があります。その差異をなるべく抑えるために textlint は役立ちます。

CCGでは Pull Request 作成時(および更新時)に textlint による文章校正が走ります。

問題が見つかった際は以下のようなコメントが飛んできます ² 。

この textlint による指摘が無くなるまで、 Pull Request はマージできないようにしています ³ 。

では 指摘が出てきたらどう対応するのか 。以降で対応策をまとめます。

第一優先で実施 ください。

指摘された項目を修正して、更新(push) してください。更新後の再チェックで指摘が無くなればOKです。

特定のワードを指摘除外にするルール ( textlint-filter-rule-allowlist ) を導入しています。

この除外設定は textlintの設定ファイル (CCGでは .textlintrc.yaml )に記載します。設定ファイルの allowlist にワードを追記します。

管理者と同意(コミュニケーション)を取った上で 、同じ Pull Request 内で .textlintrc.yaml を更新して例外登録してください。

以下、例外登録すべき or べきでないの、ざっくりとしたガイドです。

⭕ 例外登録すべき
- 正式な専門用語が引っかかる
- AWSスペルチェックで、部分一致で引っかかる
- 特殊な記法が引っかかる (例: MkDocs のハイライト記法)
- その他、特定パターンが引っかかる (※ 正規表現等で厳密に絞れる場合のみ)
❌ 例外登録すべきでない
- 文章の改善・工夫で対応できる場合

指定した範囲をチェック対象外にするルール ( textlint-filter-rule-comments ) を導入しています。

以下のように textlint-disable 〜 textlint-enable で挟みます。

ここは textlint チェック対象の文章です。

<!-- textlint-disable -->

ここは textlint チェック "対象外" の文章です。

<!-- textlint-enable -->

ここは textlint チェック対象の文章です。

管理者と同意(コミュニケーション)を取った上で 、コメントアウトを適用します。

以下、コメントアウトすべき or べきでないの、ざっくりとしたガイドです。

以上、textlint による指摘が出てきた際の対応策でした。

指摘が出ること自体は全然悪いことではないので、ガンガン執筆していきましょう！

Classmethod Cloud Guidebook(CCG)はクラスメソッドメンバーズ(請求代行サービス)向けに公開しているナレッジサイトです。詳しくはこちらの紹介ブログを参照ください。 ↩
実装参考【GitHub Actions】Markdown 執筆に textlintの自動校正を取り入れる | DevelopersIO ↩
GitHub Settings の Branch protection rule → Require status checks to pass before merging から設定 ↩